home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 November: Tool Chest / Dev.CD Nov 94.toast / Apple II / Essentials / Essentials.sea / File.Type.Notes / FTN.C7.XXXX < prev    next >
Encoding:
Text File  |  1993-06-15  |  22.8 KB  |  501 lines  |  [TEXT/GEOL]
  1. Apple II
  2. File Type Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. File Type:       $C7 (199)
  7. Auxiliary Type:  All
  8.  
  9. Full Name:       Control Panel
  10. Short Name:      Control Panel
  11.  
  12. Revised by:      Dave "Flag Bits" Lyons                              May 1992
  13. Written by:      Matt Deatherage & Darryl Lovato               September 1989
  14.  
  15. Files of this type contain control panels (formerly called CDevs) for the
  16. Apple IIgs Control Panels New Desk Accessory.
  17.  
  18. CHANGES SINCE DECEMBER 1991:   Updated for Control Panels NDA 2.0 in System
  19. 6.0.
  20. _____________________________________________________________________________
  21.  
  22. Files of type $C7 contain control panels.  When deciding whether to write an
  23. NDA or a control panel, keep in mind that control panels normally don't take
  24. any RAM when they are not in use, don't take up space in the Apple menu, and
  25. automatically re-open at the same screen position where they were last used.
  26. On the other hand, control panels are limited to a single code segment, and
  27. the main window has a fixed size.
  28.  
  29. Before System 6, the Control Panels NDA presented control panels (then called
  30. "CDevs" to the user) in a single window.  In System 6, each control panel
  31. appears in its own window.
  32.  
  33.  
  34. AUXILIARY TYPE
  35.  
  36. The auxiliary type of CDevs is defined bit by bit.  Currently, only bit 15 is
  37. defined--it's the "inactive" bit.  As with desk accessories, FSTs, and setup
  38. files, the control panel is not loaded or used if this bit is set.  All other
  39. bits are reserved and must be set to zero.  (In 6.0, inactive control panels
  40. do not appear in the Control Panels NDA's list, but the user can still open
  41. them directly from the Finder.)
  42.  
  43.  
  44. HOW CONTROL PANELS WORK
  45.  
  46. The Control Panels NDA lets the user choose control panels, and it
  47. communicates with open control panels using a small collection of messages.
  48. Most events the Control Panels NDA receives from the system are handled by
  49. calling TaskMasterDA.  At certain times, the Control Panels NDA sends messages
  50. to control panels.
  51.  
  52. The Control Panels NDA takes care of nearly everything necessary, including
  53. tracking controls.  Control panel windows are usually just windows full of
  54. extended controls; the control panel receives a HitCDEV message every time the
  55. user adjusts the value of one of the controls.
  56.  
  57. EVERY control in the control panel window must be an extended control.  Older,
  58. non-extended controls are not allowed; all controls MUST be created with
  59. NewControl2.  When one of these controls is "hit," the Control Panels NDA
  60. calls the control panel with the HitCDEV message, the control handle, and the
  61. control ID.  This allows the control panel to respond to user actions.  User
  62. interface items beyond extended controls (for example, modal windows) must be
  63. handled entirely by the control panel (that is, the Control Panels NDA is not
  64. involved).
  65.  
  66.    NOTE: Setting the fInWindowOnly bit of Pop-up menu controls is
  67.          not recommended.
  68.  
  69. THE CONTROL PANELS WINDOW
  70.  
  71. In version 1.0 of the Control Panel NDA there is a single window, and exactly
  72. one control panel is always active in a portion of that window.
  73.  
  74. With System 6, this is no longer true.  Many control panel messages include
  75. "the control panel's window pointer" as one of the parameters.  This is
  76. guaranteed to be the window containing the control panel's controls, but
  77. little else is guaranteed.
  78.  
  79. For example, do not draw outside the area containing your control panel's
  80. controls; do not compute other window sizes from the size of this window; and
  81. do not assume that the Control Panels NDA will offset your controls'
  82. coordinates by the same amount version 1.0 did.
  83.  
  84. Do not hard-code any window coordinates.  The Control Panels NDA shifts all
  85. your controls by some amount horizontally and vertically, but this amount will
  86. not stay the same between different versions of the Control Panels NDA (it can
  87. be zero).  If you draw things besides controls in the window, compute the
  88. coordinates relative to a control on the fly.
  89.  
  90. In System 6.0, each control panel gets its own window.
  91.  
  92. RESOURCE FORK
  93.  
  94. The Control Panels NDA opens your control panel's resource fork differently
  95. depending on whether the machine was booted from an AppleShare file server or
  96. from a local volume.
  97.  
  98. When the machine was booted from AppleShare, your resource fork is opened with
  99. read-only access so that more than one user can have your control panel open
  100. at once.  When the machine was booted locally, your resource fork is opened
  101. with "as allowed" access (this means you will have read/write access if the
  102. control panel file is unlocked and was not already opened read-only by some
  103. other part of the system).
  104.  
  105. When your control panel receives the BootCDEV message at boot time, its
  106. resource fork is always open read-only.
  107.  
  108.  
  109. FILE FORMAT
  110.  
  111. A control panel is defined by three resources (additional resources may be
  112. present).  The data fork is normally empty, but a control panel that requires
  113. System 6 or later may put code in the data fork in OMF format (it's up to the
  114. control panel to determine its own pathname and use InitialLoad2 to load code
  115. from the data fork--a control panel can find its pathname by using
  116. GetCurResourceFile, GetOpenFileRefNum, and GetRefInfo).
  117.  
  118. The three required resources are the CDev code resource (type rCDEVCode=$8018,
  119. ID=$00000001), the CDev flags resource (type rCDEVFlags=$8019, ID $00000001)
  120. and the CDev's icon (type rIcon=$8001, ID=$00000001).
  121.  
  122. It is a good idea to make sure each released version of your control panel
  123. file has a different creation date, since the system caches certain
  124. information about your control panel in the CDev.Data file.  The system uses
  125. the creation date to notice that a new version of your CDev is present.
  126.  
  127. You may also want to delete the *:System:CDevs:CDev.Data file, if it exists,
  128. as part of your CDev installation process.
  129.  
  130. THE ICON RESOURCE
  131.  
  132. Each control panel's icon is a standard icon resource.  This icon appears in
  133. the Control Panels window; it is also displayed at boot time if the CDev has
  134. any initialization code (described later).
  135.  
  136. If the icon is to be displayed during boot time (before System 6.0), it must
  137. be exactly 28 pixels wide.  In 6.0, this restriction is gone, but 28 is still
  138. a nice width.
  139.  
  140. THE CDEV CODE RESOURCE
  141.  
  142. The rCDevCode(1) resource contains code to do the real work.  A code resource
  143. has the same format as an OMF load file; the code resource converter (which is
  144. part of the system) is responsible for loading code resources.  Eventually,
  145. InitialLoad2 loads the code from memory.  This process gives the rCDevCode
  146. resource a maximum size of 64K.
  147.  
  148. When the control panel code gets control, the stack is as follows:
  149.  
  150.  
  151.          | Previous Contents |
  152.          |___________________|
  153.          |                   |
  154.          |-      space      -|         Long - Space for result
  155.          |___________________|
  156.          |      message      |         Word - Action for CP to take
  157.          |___________________|
  158.          |                   |
  159.          |-      data1      -|         Long - Data passed to control panel
  160.          |___________________|
  161.          |                   |
  162.          |-      data2      -|         Long - Data passed to control panel
  163.          |___________________|
  164.          |                   |
  165.          |-     RTLAddr     -|      3 Bytes - Return Address
  166.          |___________________|
  167.          |                   |   <-  Stack Pointer (SP)
  168.  
  169.  
  170.  
  171.  
  172. The control panel must remove the input parameters from the stack and perform
  173. an RTL, so the calling routine may then pull the four-byte result parameter
  174. off the stack.  Just before the control panel code RTLs, the stack must be
  175. formatted as follows:
  176.  
  177.          | Previous Contents |
  178.          |___________________|
  179.          |                   |
  180.          |-     result      -|         Long - Result from control panel
  181.          |___________________|
  182.          |                   |
  183.          |-    RTL Addr     -|      3 Bytes - Return Address
  184.          |___________________|
  185.          |                   |   <-  Stack Pointer (SP)
  186.  
  187.  
  188.  
  189. This function, like nearly all toolbox functions, is a "Pascal" function, and
  190. may be declared in Pascal as follows:
  191.  
  192.   function MyControlPanel(message: Integer; data1, data2: Longint): LongInt;
  193.  
  194. It may be declared in C as follows:
  195.  
  196.    pascal Long MyControlPanel(message, data1, data2)
  197.    int message;
  198.    long data1, data2;
  199.  
  200. Data1 and Data2 depend on the value of message; message is the parameter that
  201. tells the CDev code what needs to be done.  Higher-level language control
  202. panels can easily be arranged as a giant switch (or case, as the case may be)
  203. statement.
  204.  
  205. There are twelve defined "CDev" messages.  Where parameters are not listed,
  206. they are undefined.
  207.  
  208. MESSAGE 1:  MachineCDEV
  209.  
  210. The Control Panels NDA always compares the Apple IIgs ROM version against the
  211. minimum ROM version you put in the CDev Flags resource.  If the machine's ROM
  212. version is too low, the control panel does not appear (and cannot be opened).
  213.  
  214. The MachineCDEV message was not supported before System 6.0.  In 6.0, if the
  215. wantMachine bit is set in the CDev Flags resource, the control panel receives
  216. MachineCDEV when the user attempts to open it.  The input parameters are
  217. undefined.  Return a nonzero result to allow the open, or return zero to abort
  218. the open.  When returning zero, you may want to display an alert explaining
  219. why the control panel cannot be opened.
  220.  
  221. MESSAGE 2:  BootCDEV
  222.  
  223. If the wantBoot flag is set in the CDev Flags resource, this routine is called
  224. during the IIgs boot sequence.  The parameters are undefined before 6.0.  In
  225. 6.0, data1 is defined to point to a data word that is initialially zero.  If
  226. you set bit 0 of this word while handling the BootCDEV message, the Control
  227. Panels NDA will draw an "X" over your icon (but it will not call SysBeep2 for
  228. you; do that yourself if appropriate).
  229.  
  230. BootCDEV is called only during a real boot--it doesn't get control on a switch
  231. back to GS/OS from ProDOS 8.  The Control Panels NDA draws the icon (from the
  232. icon resource) on the boot screen.  (Before 6.0, the icon must be exactly 28
  233. pixels wide if it is drawn at boot time.)
  234.  
  235. At best, the machine state during this call can be termed bad.  QuickDraw II
  236. is not even available.  Be sure to save and restore any system resources you
  237. use, including the data bank register and the direct page register.
  238.  
  239.    NOTE: If your CDev expects to receive a BootCDEV message, it
  240.          should still behave gracefully if BootCDEV was never
  241.          received and the user attempts to use the control panel
  242.          (for example, tell the user to put the file into the
  243.          CDevs folder and restart the system).
  244.  
  245.          In System 5.0.x, the user could drag your control panel
  246.          into the CDevs folder and then try to use it without
  247.          restarting.  In System 6.0, control panels are directly
  248.          launchable from the Finder, but only the ones in the
  249.          CDevs folder receive BootCDEV messages.
  250.  
  251. MESSAGE 3: Reserved
  252.  
  253. This message is reserved for future use as a shutdown message.
  254.  
  255. MESSAGE 4:  InitCDEV
  256.  
  257. If the wantInit flag is set in the CDev Flags resource, this routine is called
  258. with data1 equal to the control panel's window pointer.  When InitCDEV is
  259. called, CreateCDEV (message 7) has already been called.  Controls should have
  260. been created in CreateCDEV, and this routine is an ideal place to initialize
  261. the controls before they are displayed.
  262.  
  263. MESSAGE 5:  CloseCDEV
  264.  
  265. This routine is called if the wantClose bit is set in the CDev Flags resource.
  266. If so, CloseCDEV is called when your control panel is closing.  This is a good
  267. place to dispose of any memory you allocated or to save settings that need to
  268. be saved.  The disposal of the control panel's controls is handled by the
  269. Control Panels NDA.  The window pointer is in data1.
  270.  
  271. MESSAGE 6:  EventsCDEV
  272.  
  273. If the wantEvents bit is set in the CDev Flags resource, the Control Panels
  274. NDA calls this routine with data1 as a pointer to the event record (this is an
  275. Event Manager event record, not a TaskMaster-style task record).  The window
  276. pointer is in data2.  The Control Panels NDA, like all NDAs, is passed events,
  277. which the it then handles by using the TaskMasterDA call.  This routine is
  278. called before TaskMasterDA is called, so the control panel can change the
  279. event record before the Control Panels NDA handles it.
  280.  
  281. MESSAGE 7:  CreateCDEV
  282.  
  283. This routine is only called if the wantCreate bit is set in the CDev Flags
  284. resource.  When called, the control panel's window pointer is in data1.  The
  285. control panel must create any controls it has during this call.  The control
  286. panel's resource fork is open during this call, so Resource Manager calls may
  287. be made (and controls may be created from resources in the control panel
  288. file).  All control rectangles are relative to the upper-left corner of the
  289. part of the window a control panel owns (in 6.0 this happens to be the whole
  290. window).  The Control Panels NDA handles setting the offsets of the controls
  291. to the proper place in the window.  Initialization of the controls must be
  292. done in the InitCDEV call.
  293.  
  294. If the wantCreate bit is not set, the control panel must contain an
  295. rControlList (type=$8003) resource with ID $00000001.  The Control Panels NDA
  296. automatically creates your controls from the resource.
  297.  
  298. MESSAGE 8:  AboutCDEV
  299.  
  300. If the wantAbout bit is set in the CDev Flags resource, the Control Panels NDA
  301. calls this routine when the user selects "Help" while your control panel's
  302. icon is selected.  The window pointer to the help window is in data1.  The
  303. Control Panels NDA takes care of the icon, author, version string and the "OK"
  304. button.  The easiest way to handle help is simply to create a static text
  305. control with the help text in it.
  306.  
  307. If the wantAbout bit is not set, your control panel must have an rControlList
  308. resource with ID $00000002.  When the user selects "Help" while your control
  309. panel's is selected, the Control Panels NDA uses this resource to create your
  310. additional About controls.
  311.  
  312.    NOTE: In 6.0, when a control panel receives the AboutCDEV
  313.          message, the Font Manager and TextEdit are always
  314.          started.  The Control Panels NDA can display a control
  315.          panel's About box without ever opening the control panel.
  316.          Making TextEdit available avoids a potential
  317.          incompatibility with some control panels (such as
  318.          General) that start up TextEdit on receiving AboutCDEV,
  319.          assuming they will have a chance to shut it back down
  320.          later, on receiving CloseCDEV.
  321.  
  322. MESSAGE 9:  RectCDEV
  323.  
  324. Normally, the Control Panels NDA uses the rectangle in the CDev Flags resource
  325. for the control panel's display rectangle.  However, if the wantRect bit is
  326. set in the CDev Flags resource, this routine is called before the control
  327. panel is displayed with data1 containing a pointer to the display rectangle.
  328. The rectangle may be modified by this routine.  This gives control panels the
  329. chance to use different sized rectangles for different occasions.  For
  330. example, on ROM 03, the serial port control panels show fewer parameters when
  331. the port is set to AppleTalk (since fewer parameters are changeable).  In that
  332. instance, the RectCDEV routine changes the rectangle to be smaller.
  333.  
  334. MESSAGE 10:  HitCDEV
  335.  
  336. If the CDev wants to know when a control has been hit, it can set the wantHit
  337. bit in the CDev Flags resource.  When called, the handle to the control in
  338. question is in data1 and that control's ID is in data2.  The control panel may
  339. then take action based upon the control selection.
  340.  
  341. If you need the window pointer, you can get it from the ctlOwner field of the
  342. control record handle in data1.
  343.  
  344. Note:  If your control panel contains any extended List controls, the toolbox
  345. automatically creates a scroll bar control for each list.  These scroll bars
  346. are standard (not extended) controls; this is the exception to the rule that
  347. all control panel controls must be extended.  When the user tracks the scroll
  348. bar, the HitCDEV data1 parameter is a valid control handle, but data2 is an
  349. unpredictable large value (because no control ID is available for a
  350. non-extended control).  In 6.0, the control ID returned in this case is always
  351. $FFFFFFFF.
  352.  
  353. MESSAGE 11:  RunCDEV
  354.  
  355. This routine is called if the wantRun bit in the CDev flags resource is set.
  356. It enables control panels to receive a call as often as the Control Panels NDA
  357. receives run events from SystemTask (currently once per second).
  358.  
  359. The control panel's window pointer is in data1.  (This is true even before
  360. 6.0, but it was not previously documented.)
  361.  
  362. MESSAGE 12:  EditCDEV (6.0 and later)
  363.  
  364. This routine is called if the wantEdit bit in the CDev flags resource is set,
  365. when the user chooses Undo, Cut, Copy, Paste, or Clear from the Edit menu (if
  366. the items have the proper item numbers), and when the user types Command-Z,
  367. -X, -C, or -V.
  368.  
  369. The control panel's window pointer is in data2.  The low word of data1
  370. indicates what kind of edit operation is happening.  The codes are the same as
  371. what SystemEdit passes to NDAs (Toolbox Reference 1, page 5-7):
  372.  
  373.      $0005     Undo
  374.      $0006     Cut
  375.      $0007     Copy
  376.      $0008     Paste
  377.      $0009     Clear
  378.  
  379. All other codes are reserved for future use.
  380.  
  381.  
  382. THE CDEV FLAGS RESOURCE
  383.  
  384. The CDEV Flags resource tells the Control Panels NDA which messages the
  385. control panel accepts.  It also tells the Control Panels NDA certain things
  386. about the operating environment required for the CDev.
  387.  
  388. flags    (+000)    Word    The flags word tells the Control Panels NDA
  389.                            which messages (defined in the discussion of
  390.                            the rCDevCode resource) the control panel
  391. wants:
  392.                            Bits 15 - 12: Reserved, must be zero.
  393.                            Bit 11:       wantEdit
  394.                                          Control panel wants edit events.
  395.                            Bit 10:       wantRun
  396.                                          Control panel wants run events.
  397.                            Bit 9:        wantHit
  398.                                          Control panel wants control hits.
  399.                            Bit 8:        wantRect
  400.                                          Control panel wants rectangle
  401.                                          messages.
  402.                            Bit 7:        wantAbout
  403.                                          Control panel wants "about"
  404.                                          messages.
  405.                            Bit 6:        wantCreate
  406.                                          Control panel wants create messages.
  407.                            Bit 5:        wantEvents
  408.                                          Control panel wants event records.
  409.                            Bit 4:        wantClose
  410.                                          Control panel wants close messages.
  411.                            Bit 3:        wantInit
  412.                                          Control panel wants initialization
  413. message.
  414.                            Bit 2:        wantShutDown
  415.                                          Reserved, must be zero.
  416.                            Bit 1:        wantBoot
  417.                                          Control panel wants boot messages.
  418.                            Bit 0:        wantMachine
  419.                                          Control panel wants machine messages
  420.                                          (6.0).
  421. enabled  (+002)    Byte    If this value is zero, the control panel is
  422.                            never activated.  NOT USED.
  423. version  (+003)    Byte    An integer version number assigned by the
  424.                            author.
  425. machine  (+004)    Byte    This byte contains a minimum ROM version
  426.                            required for the control panel.  For most
  427.                            control panels this is 1, but some
  428.                            (requiring, for example, hardware text page
  429.                            two shadowing) want 3 in this byte.
  430. reserved (+005)    Byte    Reserved, must be zero.
  431. data rect(+006) 4 Words    QuickDraw II rectangle within which the
  432.                            control panel is displayed.  The top left of
  433.                            this rectangle must be (0,0).
  434. name    (+014) 16 Bytes    A string (Pascal) giving the name of the
  435.                            control panel.  Names longer than 15 bytes
  436.                            are not allowed.  Note that this field
  437.                            requires 16 bytes regardless of the string
  438.                            length.
  439. author  (+030) 33 Bytes    A string (Pascal) giving the name of the
  440.                            control panel's author.  Names longer than
  441.                            32 bytes are not allowed.  Note that this
  442.                            field requires 33 bytes regardless of the
  443.                            string length.
  444. version (+063) 9 Bytes     A string (Pascal) giving the version of the
  445.                            control panel.  Strings are typically of the
  446.                            format "v1.0".  Version strings longer than
  447.                            eight bytes are not allowed.  Note that this
  448.                            field requires nine bytes regardless of the
  449.                            string length.
  450.  
  451. OPENING ADDITIONAL RESOURCE FILES
  452.  
  453. The Control Panels NDA, not any individual control panel, owns the Resource
  454. Manager search path that is in effect when a control panel routine gets
  455. control.  While handling a message, you may temporarily open additional
  456. resources files in the same search path, but you must close them and call
  457. SetCurResourceFile to its previous value before returning control to the
  458. Control Panels NDA.
  459.  
  460. There may be extra resource files in the search path that you know nothing
  461. about, so do not assume that your extra file is adjacent to your control
  462. panel's resource file in the search path.
  463.  
  464. COLOR TABLE SWAPPING
  465.  
  466. Since control panels generally assume the sixteen standard 640-mode dithered
  467. colors are available, Control Panels NDA 2.0 automatically provides a standard
  468. color table whenever the "Control Panels" window or any individual control
  469. panel window is in front.  (It ought to do the same thing for the Help and
  470. credits windows, but it does not.)
  471.  
  472. The color table provided in 640 mode is identical to the default 640-mode
  473. color table.
  474.  
  475. The color table provided in 320 mode provides colors almost identical to the
  476. default 640 colors.  This is not the same as the default 320-mode color table.
  477. (See Apple IIgs Technical Note #63, Table 3.)
  478.  
  479. PROGRAMMATIC INTERFACE TO THE CONTROL PANELS NDA
  480.  
  481. You can use SendRequest in the System 6 Tool Locator to ask the Control Panels
  482. NDA to do two things for you:  Open the main window, or open a control panel
  483. from a pathname.
  484.  
  485. You must send the requests by name to "Apple~Control Panel~".
  486.  
  487. Request code $9001 is cpOpenControlPanels.  dataIn is reserved and must be
  488. zero.
  489.  
  490. Request code $9000 is cpOpenCDev.  dataIn and dataOut are as defined for the
  491. finderSaysOpenFailed request (see the Finder 6.0 documentation).  You can also
  492. open a control panel by pathname by sending finderSaysBeforeOpen, as permitted
  493. in the Finder documentation.
  494.  
  495.  
  496. Further Reference
  497. _____________________________________________________________________________
  498.  
  499.    o   Apple IIgs Toolbox Reference, Volumes 1-3
  500.    o   System 6.0 Documentation
  501.